Technotes

Download Acrobat file (141K)

Download ClarisWorks 4 file (44K)

Download Technotes 1013-1026 QuickView file (284K)

Technote 1019

FEBRUARY 1996

This Technote addresses the 'SICN' resource format and how to handle 'SICN' Resources with more than one indexed icon. Use PlotSICNHandle for 'SICN' Resources with single-indexed icons. With minor modifications, the techniques in this Technote can also be used to plot a bitmap of any dimension.

If your application has the need to store more than one icon in a 'SICN' Resource, you will have to load and plot the icons yourself.

We recommend the use of the Icon Utilities package for all your icon needs. This is located in the Icon Utilities chapter ofInside Macintosh: More Macintosh Toolbox.

Contents

• About 'SICN's
  
• Using 'SICN's
  

Figure 1. A 'SICN' Fatbits representation of a dogcow

A 'SICN' resource contains any number of small icon bit images. Each small icon in a 'SICN' list describes a 16 by 16 pixel image and requires 32 bytes of storage. Like an 'ICN#' resource, there is no count of the number of icons stored in a 'SICN'. The following 'SICN' resource, in MPW Rez format, contains two small icons:

	resource 'SICN' (1984, "clarus") {
		{	/* array: 2 elements */

			$"00 48 00 B4 00 84 40 52 C0 41 A0 81 9F 8E 8F 18"
			$"40 18 40 18 47 88 48 48 48 48 44 44 3C 3C 00 00",
			$"00 48 00 FC 00 FC 40 7E C0 7F E0 FF FF FE FF F8"
			$"7F F8 7F F8 7F F8 78 78 78 78 7C 7C 3C 3C 00 00"
		}
	};

Defining a 'SICN' as an Array

Listing 1 - Pascal

TYPE
	SICN        = ARRAY[0 .. 15] of INTEGER;
	SICNList    = ARRAY[0 .. 0] of SICN;
	SICNPtr     = ^SICNList;
	SICNHand    = ^SICNPtr;

Listing 2 - C

typedef    short       SICN[16];
typedef    SICN        *SICNList;
typedef    SICNList    *SICNHand;

Counting Included Small Icons

Listing 3 - Pascal

CONST
	mySICN      = 1984;
VAR
	theSICN     : SICNHand;
	theSize     : LONGINT;
	theCount    : LONGINT;
	theIndex    : LONGINT;

theSICN := SICNHand(GetResource('SICN', mySICN));
IF (theSICN <> NIL) THEN BEGIN
	theSize := GetHandleSize(Handle(theSICN));
	theCount := theSize DIV sizeof(SICN);
END;

Listing 4 - C

#define mySICN         1984

SICNHand   theSICN;
long       theSize;
long       theCount;
long       theIndex;

theSICN = (SICNHand) GetResource('SICN', mySICN);
if (theSICN) {
	theSize = GetHandleSize((Handle)theSICN);
	theCount = theSize / sizeof(SICN);
}

Calling Plot SICN

The following is an example call to PlotSICN which plots all the small icons in a resource into the same rectangle:

Listing 5 - Pascal

SetRect(theRect, 0, 0, 16, 16);
FOR theIndex := 0 TO theCount-1 DO
	PlotSICN(theRect, theSICN, theIndex);

Listing 6 - C

SetRect(&theRect, 0, 0, 16, 16);
for (theIndex = 0; theIndex < theCount ; ++theIndex)
	PlotSICN(&theRect, theSICN, theIndex);

Locking the Handle to 'SICN'

To play it safe, PlotSICN saves a copy of the master pointer flags associated with the relocatable block, locks the block with a call to HLock, and restores the flags after calling CopyBits.

Warning:

You should never examine, set, or clear these flags directly; you should always use the routines which are provided by the Memory Manager and Resource Manager. It is not necessary to check the value of the flag after getting it.

Listing 7 - Pascal

PROCEDURE PlotSICN(theRect: Rect; theSICN: SICNHand; theIndex : INTEGER);
VAR
	state       : SignedByte;	{we want a chance to restore original
														state }
	srcBits     : BitMap;	{built up around 'SICN' data so we can
														CopyBits }

BEGIN
	{check the index for a valid value }
	IF (GetHandleSize(Handle(theSICN)) DIV sizeof(SICN)) > theIndex THEN
	BEGIN

	{store the resource's current locked/unlocked condition }
	state := HGetState(Handle(theSICN));

	{lock the resource so it won't move during the CopyBits call }
	HLock(Handle(theSICN));

	{set up the small icon's bitmap }
	{$PUSH}
	{$R-}			{turn off range checking }
	srcBits.baseAddr := Ptr(@theSICN^^[theIndex]);
	{$POP}
	srcBits.rowBytes := 2;
	SetRect(srcBits.bounds, 0, 0, 16, 16);

	{draw the small icon in the current grafport }
	CopyBits(srcBits,thePort^.portBits,srcBits.bounds,
			theRect,srcCopy,NIL);

	{restore the resource's locked/unlocked condition }
	HSetState(Handle(theSICN), state);
	END;
END;

Listing 8 - C

void PlotSICN(Rect *theRect, SICNHand theSICN, long theIndex) {
	char    state;		/* saves original flags of 'SICN' handle */
	BitMap    srcBits;	/* built up around 'SICN' data so we can CopyBits */

	/* check the index for a valid value */
	if ((GetHandleSize(Handle(theSICN)) / sizeof(SICN)) > theIndex) {

		/* store the resource's current locked/unlocked condition */
		state = HGetState((Handle)theSICN);

		/* lock the resource so it won't move during the CopyBits call */
		HLock((Handle)theSICN);

		/* set up the small icon's bitmap */
		srcBits.baseAddr = (Ptr) (*theSICN)[theIndex];
		srcBits.rowBytes = 2;
		SetRect(&srcBits.bounds, 0, 0, 16, 16);

		/* draw the small icon in the current grafport */
		CopyBits(&srcBits,&(*qd.thePort).portBits,
			&srcBits.bounds,theRect,srcCopy,nil);

		/* restore the resource's locked/unlocked condition */
		HSetState((Handle) theSICN, state);
	}
}

• Inside Macintosh: Macintosh ToolBox Essentials
• Inside Macintosh: Imaging With QuickDraw
• Inside Macintosh: Memory
• Technical Note QD 17 -- Drawing Icons

Change History

Since August 1989: Errors in the Pascal code were corrected.